home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 April: Technology Seed / Mac Tech Seed Apr '97.toast / QuickTime™ VR 2.0 SDK / Documentation + Extras / Updated Interfaces / QuickDraw 3D 1.5 Interfaces / Interfaces / QD3DExtension.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-24  |  12.2 KB  |  405 lines  |  [TEXT/MPS ]

  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DExtension.h                                             **
  4.  **                                                                          **
  5.  **                                                                          **
  6.  **     Purpose:     QuickDraw 3D Plug-in Architecture                         **
  7.  **                                                                          **
  8.  **                                                                          **
  9.  **                                                                          **
  10.  **     Copyright (C) 1992-1996 Apple Computer, Inc.  All rights reserved.     **
  11.  **                                                                          **
  12.  **                                                                          **
  13.  *****************************************************************************/
  14. #ifndef QD3DExtension_h
  15. #define QD3DExtension_h
  16.  
  17. #if defined(PRAGMA_ONCE) && PRAGMA_ONCE
  18.     #pragma once
  19. #endif  /*  PRAGMA_ONCE  */
  20.  
  21. #include "QD3DErrors.h"
  22.  
  23.  
  24. #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH
  25.  
  26. #if defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  27.     #pragma options enum=small
  28. #endif
  29.     #include <CodeFragments.h>
  30. #if defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  31.     #pragma options enum=reset
  32. #endif
  33.  
  34. #endif /* WINDOW_SYSTEM_MACINTOSH */
  35.  
  36. #if defined(THINK_C) || defined(__SC__)
  37.     #pragma options(!pack_enums, !align_arrays)
  38.     #pragma SC options align=power
  39. #elif defined(__MWERKS__)
  40.     #pragma enumsalwaysint on
  41.     #pragma align_array_members off
  42.     #pragma options align=native
  43. #elif defined(__PPCC__)
  44.     #pragma options align=power
  45. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  46.     #pragma options enum=int
  47. #endif
  48.  
  49. #ifdef __cplusplus
  50. extern "C" {
  51. #endif  /* __cplusplus  */
  52.  
  53. /******************************************************************************
  54.  **                                                                             **
  55.  **                                Constants                                      **
  56.  **                                                                             **
  57.  *****************************************************************************/
  58.  
  59. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  60.  
  61. #define kQ3XExtensionMacCreatorType        Q3_OBJECT_TYPE('Q','3','X','T')
  62. #define kQ3XExtensionMacFileType        Q3_OBJECT_TYPE('s','h','l','b')
  63.  
  64. #endif  /*  OS_MACINTOSH  */
  65.  
  66.  
  67. /******************************************************************************
  68.  **                                                                             **
  69.  **                                    Macros                                      **
  70.  **                                                                             **
  71.  *****************************************************************************/
  72.  
  73. /*
  74.  * Use this Macro to pack the version number for your class.  This would most
  75.  * likely get used in the  kQ3XMethodTypeObjectClassVersion to return the 
  76.  * version for your class.  This method is set up in your meta handler.
  77.  */
  78.  
  79. #define Q3_OBJECT_CLASS_VERSION(major, minor)            \
  80.     (unsigned long) (((major) << 16) | (minor))
  81.  
  82. /*
  83.  * Convenience macros to unpack a version number, accessing the major and the
  84.  * minor version numbers
  85.  */
  86. #define Q3_OBJECT_CLASS_GET_MAJOR_VERSION(version)        \
  87.     (unsigned long) ((version) >> 16)
  88.  
  89. #define Q3_OBJECT_CLASS_GET_MINOR_VERSION(version)        \
  90.     (unsigned long) ((version) & 0x0000ffff)
  91.  
  92.  
  93.  
  94. /******************************************************************************
  95.  **                                                                             **
  96.  **                                Object Method types                              **
  97.  **                                                                             **
  98.  *****************************************************************************/
  99.  
  100. #define kQ3XMethodTypeObjectClassVersion        Q3_METHOD_TYPE('v','r','s','n')
  101. typedef unsigned long    TQ3XObjectClassVersion;
  102.  
  103. #define kQ3XMethodTypeObjectClassRegister        Q3_METHOD_TYPE('r','g','s','t')
  104. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectClassRegisterMethod)(
  105.     TQ3XObjectClass        objectClass,
  106.     void                *classPrivate);
  107.  
  108. #define kQ3XMethodTypeObjectClassReplace        Q3_METHOD_TYPE('r','g','r','p')
  109. typedef void (QD3D_CALLBACK *TQ3XObjectClassReplaceMethod)(
  110.     TQ3XObjectClass        oldObjectClass,
  111.     void                *oldClassPrivate,
  112.     TQ3XObjectClass        newObjectClass,
  113.     void                *newClassPrivate);
  114.  
  115. #define kQ3XMethodTypeObjectClassUnregister        Q3_METHOD_TYPE('u','n','r','g')
  116. typedef void (QD3D_CALLBACK *TQ3XObjectClassUnregisterMethod)(
  117.     TQ3XObjectClass        objectClass,
  118.     void                *classPrivate);
  119.     
  120. #define kQ3XMethodTypeObjectNew                    Q3_METHOD_TYPE('n','e','w','o')
  121. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectNewMethod)(
  122.     TQ3Object            object,
  123.     void                *privateData,        
  124.     void                *parameters);        
  125.  
  126. #define kQ3XMethodTypeObjectDelete                Q3_METHOD_TYPE('d','l','t','e')
  127. typedef void (QD3D_CALLBACK *TQ3XObjectDeleteMethod)(
  128.     TQ3Object            object,
  129.     void                *privateData);
  130.     
  131.  
  132. #define kQ3XMethodTypeObjectDuplicate            Q3_METHOD_TYPE('d','u','p','l')
  133. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectDuplicateMethod)(
  134.     TQ3Object            fromObject,
  135.     const void            *fromPrivateData,
  136.     TQ3Object            toObject,
  137.     const void            *toPrivateData);
  138.  
  139. typedef TQ3Status (QD3D_CALLBACK *TQ3XSharedLibraryRegister)(
  140.     void);
  141.  
  142.  
  143. /******************************************************************************
  144.  **                                                                             **
  145.  **                            Object Hierarchy Registration                      **
  146.  **                                                                             **
  147.  *****************************************************************************/
  148.  
  149. /*
  150.  *    Q3XObjectHierarchy_RegisterClass
  151.  *    
  152.  *    Register an object class in the QuickDraw 3D hierarchy.
  153.  *    
  154.  *    parentType            - an existing type in the hierarchy, or 0 to subclass
  155.  *                            TQ3Object
  156.  *    objectType            - the new object class type, used in the binary 
  157.  *                        metafile.  This is assigned at run time and returned
  158.  *                          to you.
  159.  *    objectName            - the new object name, used in the text metafile
  160.  *    metaHandler            - a TQ3XMetaHandler (may be NULL for some classes) 
  161.  *                          which returns non-virtual methods
  162.  *    virtualMetaHandler    - a TQ3XMetaHandler (may be NULL as well) which returns
  163.  *                            virtual methods a child would inherit
  164.  *    methodsSize            - the size of the class data needed (see 
  165.  *                            GetClassPrivate calls below)
  166.  *    instanceSize        - the size of the object instance data needed (see 
  167.  *                            GetPrivate calls below)
  168.  */
  169. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObjectHierarchy_RegisterClass(
  170.     TQ3ObjectType            parentType,
  171.     TQ3ObjectType            *objectType,
  172.     char                    *objectName,
  173.     TQ3XMetaHandler            metaHandler,
  174.     TQ3XMetaHandler            virtualMetaHandler,
  175.     unsigned long            methodsSize,
  176.     unsigned long            instanceSize);
  177.  
  178. /*
  179.  *    Q3XObjectHierarchy_UnregisterClass
  180.  *    
  181.  *    Returns kQ3Failure if the objectClass still has objects 
  182.  * around; the class remains registered.
  183.  */
  184. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectHierarchy_UnregisterClass(
  185.     TQ3XObjectClass            objectClass);
  186.  
  187. /*
  188.  *    Q3XObjectHierarchy_GetMethod
  189.  *    
  190.  *    For use in TQ3XObjectClassRegisterMethod call
  191.  */
  192. QD3D_EXPORT TQ3XFunctionPointer QD3D_CALL Q3XObjectClass_GetMethod(
  193.     TQ3XObjectClass            objectClass,
  194.     TQ3XMethodType            methodType);
  195.  
  196. /*
  197.  *    Q3XObjectHierarchy_NewObject
  198.  *    
  199.  *    To create a new object. Parameters is passed into the 
  200.  *    TQ3XObjectNewMethod as the "parameters" parameter.
  201.  */
  202. QD3D_EXPORT TQ3Object QD3D_CALL Q3XObjectHierarchy_NewObject(
  203.     TQ3XObjectClass            objectClass,
  204.     void                    *parameters);
  205.  
  206. /*
  207.  *    Q3XObjectClass_GetLeafType
  208.  *    
  209.  *    Return the leaf type of a class.
  210.  */
  211. QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3XObjectClass_GetLeafType(
  212.     TQ3XObjectClass            objectClass);
  213.  
  214. /*
  215.  *    Q3XObjectClass_GetVersion
  216.  *    This routine obtains the the version of a class, referenced by an
  217.  *    object class type.  Functions for getting the type are in QD3D.h,
  218.  *    if you have the class name.
  219.  */ 
  220. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectHierarchy_GetClassVersion(
  221.     TQ3ObjectType            objectClassType,
  222.     TQ3XObjectClassVersion    *version);
  223.  
  224. /*
  225.  *    Q3XObjectClass_GetType 
  226.  *
  227.  *    This can be used to get the type, given a reference 
  228.  *    to a class.  This is most useful in the instance where you register a 
  229.  *    an element/attribute and need to get the type.  When you register an
  230.  *    element, QD3D will take the type you pass in and modify it (to avoid
  231.  *    namespace clashes).  Many object system calls require an object type
  232.  *    so this API call allows you to get the type from the class referernce
  233.  *    that you will ordinarily store when you register the class.
  234.  */
  235. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectClass_GetType( 
  236.     TQ3XObjectClass         objectClass, 
  237.     TQ3ObjectType             *type);
  238.  
  239. #if defined(ESCHER_VER_FUTURE) && ESCHER_VER_FUTURE
  240.  
  241. /*
  242.  *    Q3XObjectClass_GetSubClassType
  243.  *    Q3XObject_GetSubClassType
  244.  *    
  245.  *    Return the subclass type of "targetObject" or "targetObjectClass"
  246.  *    
  247.  *    Used for "GetType" calls for a particular class. e.g.
  248.  *    
  249.  *    Q3Geometry_GetType would be implemented:
  250.  *    
  251.  *        TQ3ObjectType Q3Geometry_GetType(
  252.  *            TQ3GeometryObject            object)
  253.  *        {
  254.  *            return Q3XObjectHierarchy_GetObjectType(gGeometryClass, object);
  255.  *        }
  256.  *
  257.  *    where gGeometryClass is the geometry object class, and "object" is
  258.  *    a subclass of the geometry class. The type returned is the "direct"
  259.  *    subclass type of the geometry.
  260.  */ 
  261. QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3XObjectClass_GetSubClassType(
  262.     TQ3XObjectClass            objectClass,
  263.     TQ3XObjectClass            targetObjectClass);
  264.  
  265. QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3XObject_GetSubClassType(
  266.     TQ3XObjectClass            objectClass,
  267.     TQ3Object                targetObject);
  268.     
  269. #endif  /*  ESCHER_VER_FUTURE  */
  270.  
  271. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObjectHierarchy_FindClassByType(
  272.     TQ3ObjectType            type);
  273.  
  274.  
  275.  
  276. /*
  277.  *    Q3XObjectClass_GetPrivate
  278.  *    
  279.  *    Return a pointer to private instance data, a block of instanceSize bytes, 
  280.  *    from the Q3XObjectHierarchy_RegisterClass call.
  281.  *    
  282.  *    If instanceSize was zero, NULL is always returned.
  283.  */
  284. QD3D_EXPORT void *QD3D_CALL Q3XObjectClass_GetPrivate(
  285.     TQ3XObjectClass            objectClass,
  286.     TQ3Object                targetObject);
  287.         
  288. /*
  289.  * Return the "TQ3XObjectClass" of an object
  290.  */
  291. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObject_GetClass(
  292.     TQ3Object         object);
  293.     
  294. #if defined(ESCHER_VER_FUTURE) && ESCHER_VER_FUTURE
  295. /*
  296.  *    Q3XObject_GetClassPrivate
  297.  *    Q3XObjectClass_GetClassPrivate
  298.  *    
  299.  *    Return pointers to private class data, a block of methodsSize bytes, from
  300.  *    the Q3XObjectHierarchy_RegisterClass call.
  301.  *    
  302.  *    If methodsSize was zero, NULL is always returned.
  303.  */
  304. QD3D_EXPORT void *QD3D_CALL Q3XObject_GetClassPrivate(
  305.     TQ3XObjectClass            objectClass,
  306.     TQ3Object                targetObject);
  307.  
  308. QD3D_EXPORT void *QD3D_CALL Q3XObjectClass_GetClassPrivate(
  309.     TQ3XObjectClass            objectClass,
  310.     TQ3XObjectClass            targetObjectClass);
  311.  
  312. /*
  313.  * Return a pointer to an object's private data structure.
  314.  */
  315. QD3D_EXPORT void *QD3D_CALL Q3XObject_Peek(
  316.     TQ3Object         object);
  317.     
  318. #endif  /*  ESCHER_VER_FUTURE  */
  319.  
  320.  
  321. /******************************************************************************
  322.  **                                                                             **
  323.  **                    Shared Library Registration Entry Point                      **
  324.  **                                                                             **
  325.  *****************************************************************************/
  326.  
  327. typedef struct TQ3XSharedLibraryInfo {
  328.     TQ3XSharedLibraryRegister    registerFunction;    
  329.     unsigned long                sharedLibrary;
  330. } TQ3XSharedLibraryInfo;
  331.  
  332. QD3D_EXPORT TQ3Status QD3D_CALL Q3XSharedLibrary_Register(
  333.     TQ3XSharedLibraryInfo    *sharedLibraryInfo);
  334.  
  335. QD3D_EXPORT TQ3Status QD3D_CALL Q3XSharedLibrary_Unregister(
  336.     unsigned long            sharedLibrary);
  337.     
  338.  
  339. /******************************************************************************
  340.  **                                                                             **
  341.  **                                Posting Errors                                  **
  342.  **                                                                             **
  343.  **            You may only call these functions from within an extension         **
  344.  **                                                                             **
  345.  *****************************************************************************/
  346.  
  347. /*
  348.  *    Q3XError_Post
  349.  *    
  350.  *    Post a QuickDraw 3D Error from an extension.
  351.  */
  352. QD3D_EXPORT void QD3D_CALL Q3XError_Post(
  353.     TQ3Error        error);
  354.  
  355. /*
  356.  *    Q3XWarning_Post
  357.  *    
  358.  *    Post a QuickDraw 3D Warning, from an extension.  Note the warning code you
  359.  *    pass into this routine must already be defined in the table above.
  360.  */
  361. QD3D_EXPORT void QD3D_CALL Q3XWarning_Post(
  362.     TQ3Warning        warning);
  363.  
  364. /*
  365.  *    Q3XNotice_Post
  366.  *    
  367.  *    Post a QuickDraw 3D Notice, from an extension.  Note the notice code you
  368.  *    pass into this routine must already be defined in the table above.
  369.  */
  370. QD3D_EXPORT void QD3D_CALL Q3XNotice_Post(
  371.     TQ3Notice        notice);
  372.  
  373.  
  374. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  375.  
  376. /*
  377.  *    Q3XMacintoshError_Post
  378.  *    
  379.  *    Post the QuickDraw 3D Error, kQ3ErrorMacintoshError, and the Macintosh
  380.  *    OSErr macOSErr. (Retrieved with Q3MacintoshError_Get)
  381.  */
  382. QD3D_EXPORT void QD3D_CALL Q3XMacintoshError_Post(
  383.     OSErr            macOSErr);
  384.  
  385. #endif  /*  OS_MACINTOSH  */
  386.  
  387.  
  388. #ifdef __cplusplus
  389. }
  390. #endif  /* __cplusplus  */
  391.  
  392. #if defined(THINK_C) || defined(__SC__)
  393.     #pragma SC options align=reset
  394. #elif defined(__MWERKS__)
  395.     #pragma enumsalwaysint reset
  396.     #pragma align_array_members reset
  397.     #pragma options align=reset
  398. #elif  defined(__PPCC__)
  399.     #pragma options align=reset
  400. #elif defined(__xlc) || defined(__xlC) || defined(__xlC__) || defined(__XLC121__)
  401.     #pragma options enum=reset
  402. #endif
  403.  
  404. #endif  /* QD3DExtension_h  */
  405.